home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Experimental BBS Explossion 3
/
Experimental BBS Explossion III.iso
/
c
/
pcl4c40.zip
/
PCL4C.USR
< prev
next >
Wrap
Text File
|
1993-10-25
|
82KB
|
2,041 lines
Personal Communications Library
For the C Language
(PCL4C)
USERS MANUAL
Version 4.0
Oct 18, 1993
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 1993
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Voice 205-881-4630
FAX 205-881-4630
BBS 205-880-9748
PCL4C Users Manual Page 1
C O N T E N T S
Chapter Page
1.0 Introduction................................................3
1.1 User Support............................................4
1.2 A Typical Application...................................5
1.3 Installation............................................6
2.0 Library Organization........................................7
2.1 Configuration...........................................7
2.2 Initialization & Termination............................7
2.3 Modem Control & Status..................................8
2.4 Serial I/O..............................................8
2.5 Error Detection.........................................9
2.6 General Support.........................................9
3.0 Library Overview...........................................10
3.1 Memory Models..........................................10
3.2 Compilers Supported....................................11
3.3 Using the Library......................................12
3.4 Example Programs.......................................12
3.5 Compiling & Linking....................................13
4.0 Talking to Your Modem......................................14
4.1 Modem Standards........................................14
4.2 Flow Control...........................................15
4.3 Modem Initialization...................................16
5.0 Problems...................................................17
6.0 Serial Communications......................................18
6.1 Communications Basics..................................18
6.2 Standard Port Addresses................................19
6.3 Running 3 or 4 Ports Concurrently......................20
6.4 Using the DigiBoard....................................21
6.5 Transmitter Interrupts.................................22
6.6 RS232 Signals..........................................23
6.7 National INS8250, INS16450, and INS16550 UARTs.........24
6.8 Register Summary.......................................25
7.0 Terminal Emulator Program (TERM)...........................27
8.0 Legal Issues...............................................28
8.1 Registration...........................................28
8.2 Referral Program.......................................28
8.3 License................................................29
8.4 Warranty...............................................29
9.0 Summary....................................................30
9.1 Revision History.......................................30
9.2 Function Summary.......................................32
9.3 Further Reading........................................32
10.0 Other MarshallSoft Computing products for C................33
10.1 The Personal Protocol Library for C...................33
10.2 The LZW Data Compression Library for C................33
10.3 The EMS Expanded Memory Library for C.................34
PCL4C Users Manual Page 2
1.0 Introduction
The Personal Communications Library for the C Language (PCL4C) is
an asynchronous communications library designed for experienced
software developers programming in C. Five compilers are
supported: Microsoft C, Quick C, Borland C, Turbo C, and MIX Power
C. An IBM PC/XT/AT or compatible is required. The PCL features:
o SMALL, COMPACT, MEDIUM, and LARGE memory models.
o 37 communications and support functions.
o Supports the high performance INS16550 UART.
o Supports the PC/4 and PC/8 DigiBoard.
o Supports hardware (RTS/CTS) flow control.
o Interrupt driven receiver & (optionally) transmitter.
o Supports 300 baud to 115,200 baud.
o Supports COM1 through COM4 (through COM10 with DigiBoard).
o Adjustable receive queues from 8 bytes to 32 KB.
o Control-BREAK error exit.
o 18 communications error conditions trapped.
o Allows 4 ports to run concurrently (10 with DigiBoard).
o Complete modem control & status.
o Written in assembly language for small size & high speed.
o Terminal program featuring ASCII (with XON/XOFF), XMODEM,
YMODEM, & YMODEM-G.
Why should you buy PCL4C ? I can give you several good reasons.
COMPLETE - PCL4C is complete since it provides absolute control
of the serial ports (including the high performance
INS16550).
COMPACT - PCL4C is very compact at less than 6 KB. Your
application doesn't carry a lot of excess code.
FAST - PCL4C is fast since it will run at 38400 baud on
even slow 8088 PCs (4.77 MHZ) and at 115200 baud on
most everything else.
SUPPORT - If you get stuck, you talk to the programmer that
wrote the code, not a person hired to answer the
phone.
BBS - A BBS is available (2400 to 9600 baud, N81) in order
to provide immediate support as necessary.
NEWSLETTER - One year subscription to the MSC newsletter
discusses communications problems and solutions
(published quarterly).
PRICE - You get PCL4C for a very reasonable price !
UPGRADES - Once you buy PCL4C, you can always update to the most
recent version for little more than the cost of
sending it out to you.
PCL4C Users Manual Page 3
1.1 User Support
We want you to be successful in developing your applications using
PCL4C! We depend on our customers to let us know what they need
in a communications library. This means we are committed to
providing the best communications library that we can. If you have
any suggestions or comments, please let us know.
If you are having a problem using PCL4C, call us at 205-881-4630
between 5 PM and 9 PM CST Monday through Saturday, or FAX us at
the same telephone number at any time (24 hours). You can also
call at other times and leave a message, and call back later for a
reply. However, we can only answer questions with respect to using
the PCL4C library. We cannot help you program your application.
You may also call our User Support BBS (2400 to 9600 baud, no
parity, 8 data bits, 1 stop bit) at 205-880-9748 and leave a
message (address it to the SYSOP). We will usually have a reply
ready for you within 24 hours.
The BBS is available 24 hours per day except at 2 PM Sundays for
maintenanace. All files are in standard ZIP format. The BBS will
contain the latest shareware version of all MarshallSoft products
as well as related files such as:
BUGS.ZIP -- Bug report.
NEWS.ZIP -- Latest news regarding our products.
The MarshallSoft Computing, Inc. newsletter "Comm Talk" is
published quarterly. It discusses various communications problems
and solutions using PCL4C as well as related information.
Registered users receive a one year complimentary subscription
when first registering and for each update purchased.
Of course, you can always write to us. You should receive a reply
within a week or so.
PCL4C Users Manual Page 4
1.2 A Typical Application
In general, there are two classes of applications that use a
communications library like PCL4C -- those that use a modem to
connect to the outside world and those that connect directly to a
peripheral device. In either case, a typical application program
using PCL4C might look like the following code outline:
*****************************************************
* #include "pcl4c.h" *
* *
* char Buffer[1024]; *
* main() *
* {/* initialize serial comm system */ *
* SioRxBuf(Port,Buffer,Size1024); *
* SioParms(Port,NoParity,OneStopBit,WordLength8); *
* SioReset(Port,Baud2400); *
* *
* ...application code... *
* *
* /* terminate serial comm system */ *
* SioDone(Port); *
* } *
*****************************************************
In the above example, SioRxBuf is called to set up the a 1024 byte
receive buffer; SioParms is called to set up the parity, stop bit
count, and word length; SioReset is called to set the baud rate to
2400 and reset the UART (Univeral Asynchronous Receiver /
Transmitter).
Before leaving your application, SioDone is called to restore the
prior state of the serial communications system.
If you are using a modem, you also need to be concerned about
initializing your modem correctly and handling any required flow
control. Refer to the "Talking to Your Modem" chapter for detailed
information.
If you are using the versions of the library with transmitter
interrupts enabled (PCL4C_S2.LIB, PCL4C_M2.LIB, PCL4C_C2.LIB, and
PCL4C_L2.LIB), then SioTxBuf() must be called to set up the
transmitter buffer.
PCL4C Users Manual Page 5
1.3 Installation
(1) Before installation of PCL4C , your C compiler should already
be installed on your system and tested. If you are not familiar
with makefiles, refer to your compiler manual. If you are using
the interactive environment for Quick C or Turbo C, be sure to
compile with the memory model corresponding to the PCL4C library
used, and include the correct library in the project file. Examine
the file "FILES.LST" for a list of all the distribution files.
(2) Make a backup copy of your distribution disk. Put your
original distribution disk in a safe place.
(3) Create a work directory on your work disk (normally your
harddisk). For example, to create a work directory named PCL4C, we
first log onto the work disk and then type:
MKDIR PCL4C
(4) Copy all the files from your backup copy of the distribution
disk to your work directory. For example, to copy from the A:
drive to your work directory, we type:
CD PCL4C
COPY A:*.*
(5) [OPTIONAL] Delete the makefiles that you won't need. For
example, if you use the Microsoft C compiler, then you want to
keep all makefiles ending *._M_ but can delete those for Turbo C
(*._T_), Quick C (*._Q_), and MIX Power C (X_*.BAT). You may also
delete any libraries that you won't need.
(6) Compile SIMPLE.C and link with the appropriate PCL4C library
(PCL4C_S.LIB for all but Power C which must use PCL4C_S.MIX).
Makefiles (or project files) are provided for each of the
supported compilers (Borland C & Turbo C use the same makefiles).
a) Microsoft C: Type MAKE SIMPLE._M_
b) Microsoft Quick C: Type MAKE SIMPLE._Q_
c) Borland & Turbo C: Type MAKE -FSIMPLE._T_
d) MIX Power C: Type X_SIMPLE
SIMPLE.C should compile without any problems as all example code
has been tested with each of the supported compilers.
(7) The recommended way to test SIMPLE is to run it on two
computers connected by a null modem cable. Whatever is typed on
one computer should be displayed on the other.
PCL4C Users Manual Page 6
2.0 Library Organization
The PCL4C library is organized into six categories of functions.
Refer to the PCL Reference Manual (PCL4C.REF) for details on
individual functions.
2.1 Configuration
There are three functions in the configuration category. SioPorts
sets the number of PC and DigiBoard ports. SioUART is used to
change the UART base address for a communications port to a
non-standard address, while SioIRQ is used to assign a nonstandard
IRQ line to a port. (See the chapter IBM Communications Ports for
more details on standard UART addresses and IRQ lines).
The configuration functions SioPorts, SioUART and SioIRQ must be
called before calling any other library functions. Be very
careful in using these functions. Remember that your serial
hardware must support the UART and IRQ that you specify. Always
test any new configuration immediately.
SioPorts -- Sets number of PC and DigiBoard ports.
SioUART -- Sets the UART base address.
SioIRQ -- Assigns an IRQ line to a port.
THE IRQ GOLDEN RULE: You may open (via SioReset) only one port per
IRQ (except for the DigiBoard).
2.2 Initialization & Termination
There are eight functions in the initialization and termination
category. Together, SioParms, SioFIFO, SioRxBuf, SioTxBuf, and
SioReset initialize your serial communications system. Your
application must call SioParms and SioRxBuf before calling
SioReset, and SioReset must be called before any serial I/O
processing can be done.
After initialization, SioParms and SioBaud can be called again to
change the communications parameters without resetting the serial
port. SioFlow can be called to enable hardware flow control.
Before exiting from your application, SioDone must be called.
Failure to call SioDone can crash your system later.
SioRxBuf -- Sets up receive buffer.
SioTxBuf -- Sets up transmitter buffer.
SioFIFO -- Sets the interrupt level for the INS16550.
SioParms -- Sets parity, stop bits, and word length.
SioReset -- Initialize a serial port for processing.
SioDone -- Terminates further serial processing.
SioBaud -- Sets the baud rate of the selected port.
SioFlow -- Enables / disables flow control.
PCL4C Users Manual Page 7
2.3 Modem Control & Status
There are eight functions in the modem control and status category
which provide your application with complete control over the
status and control bits of your modem.
There are two modem control bits, "Data Terminal Ready" (DTR) and
"Request To Send" (RTS). These bits can be read, set, or cleared
by SioDTR and SioRTS.
There are four modem status bits, "Data Set Ready" (DSR), "Clear
To Send" (CTS), "Ring Indicator" (RI), and "Data Carrier Detect"
(DCD). SioModem can read any of the modem status bits. SioDSR,
SioCTS, SioRI, and SioDCD can only read their respective modem
status bit.
Refer to the chapter entitled "RS232 Signals" for a discussion of
each of the control and status bits.
SioDTR -- Set, clear, or read the Data Terminal Ready (DTR) bit.
SioRTS -- Sets, clears, or reads the Request to Send (RTS) line.
SioModem -- Reads the modem status register.
SioDSR -- Reads the Data Set Ready (DSR) modem status bit.
SioCTS -- Reads the Clear to Send (CTS) modem status bit
SioDCD -- Reads the Data Carrier Detect (DCD) modem status bit.
SioRI -- Reads the Ring Indicator (RI) modem status bit.
SioRead -- Reads the contents of the 7 UART registers.
2.4 Serial I/O
There are eight library functions in the serial I/O category.
Together, these functions give the programmer complete control
over serial I/O. Higher level functions such as protocols and
smart modem communications can be completely implemented in terms
of these functions. Refer to the example code.
SioGetc and SioPutc perform all the actual serial I/O. SioUnGetc
"ungets" the last serial byte read. SioRxFlush clears the receive
queue while SioTxFlush clears the transmit queue. SioLine can be
used to test for UART errors. SioRxQue returns the number of
bytes in the receive queue while SioTxQue returns the number of
bytes in the transmit queue.
SioGetc -- Reads the next character from the serial line.
SioPutc -- Transmit a character over a serial line.
SioUnGetc -- "Un-gets" (puts back) a specified character.
SioRxFlush -- Flush (clears) the receive buffer.
SioRxQue -- Returns the number of characters in the RX queue.
SioTxFlush -- Flush (clears) the transmit buffer.
SioTxQue -- Returns the number of characters in the TX queue.
SioLine -- Reads the line status register.
PCL4C Users Manual Page 8
2.5 Error Detection
There are four functions in the error detection category. They are
concerned with detecting or reporting communications errors. Use
of these functions can make your application significantly more
robust.
SioBrkKey can be used as an "emergency" exit from your
application. SioBrkSig can read or modify the UART break bit. This
is useful for signalling the remote system that a fatal condition
has occurred. SioLoopBack can be used to test the integrity of
your UART. SioError displays a error message corresponding to an
error code returned from a PCL4C function (every PCL4C function
returns a code).
SioBrkKey -- Returns non-zero if the Control-BREAK key was pressed
SioBrkSig -- Asserts, cancels, or detects the RS232 BREAK signal.
SioError -- Displays error in text.
SioLoopBack -- Performs a UART loopback test.
2.6 General Support
There are six functions in the general support category. Strictly
speaking, they are not communications functions but are provided
in the PCL4C library because they are not always available
(especially in some older compiler run-time libraries). At any
rate, they take up a very small amount of additional memory.
Registered users can also remove these functions from the library
if needed.
SioInfo -- Returns the library version & memory model.
SioCrtWrite -- Write character to the screen.
SioDelay -- Delays one or more tics (18.2 tics per second).
SioKeyPress -- Detects if keyboard key has been pressed.
SioKeyRead -- Reads the keyboard.
SioTimer -- Returns the number of system clock tics.
PCL4C Users Manual Page 9
3.0 Library Organization
3.1 Memory Models
Because of the segmented architecture of the INTEL CPU, there are
four memory organizations possible for computer programs. These
are named the SMALL, COMPACT, MEDIUM, and LARGE memory models,
which correspond to the four combinations of "near" and "far"
addresses for code and data.
Each executable is composed of one or more segments, where each
segment can occupy from one byte to 64 KB of memory. A "near"
address is a 16 bit offset in a segment, whereas a "far" address
consists of both a 16 bit segment value and a 16 bit offset.
In the small memory model, code and data each occupy one segment.
Thus, near addresses are allocated for both code and data.
In the compact memory model, code occupies one segment while data
may occupy multiple segments. Near addresses are allocated for
code but far addresses are allocated for data.
In the medium memory model, data occupies one segment while code
may occupy multiple segments. Near addresses are allocated for
data but far addresses are allocated for code.
In the large memory model, data and code each occupy multiple
segments. Far addesses are allocated for both code and data.
Thus, both code and data can use as many segments as required.
Refer to your compiler manual for a discussion of the memory
models supported by your compiler.
PCL4C is organized as four separate libraries (PCL4C_S.LIB,
PCL4C_C.LIB, PCL4C_M.LIB and PCL4C_L.LIB) corresponding to the
four standard memory models. For the MIX Power C compiler, the
small, medium, and large models are provided (PCL4C_S.MIX,
PCL4C_M.MIX and PCL4C_L.MIX). MIX doesn't support the compact
memory model.
MODEL CODE DATA Library
Small Near Near PCL4C_S.LIB & PCL4C_S.MIX
Compact Near Far PCL4C_C.LIB
Medium Far Near PCL4C_M.LIB & PCL4C_M.MIX
Large Far Far PCL4C_L.LIB & PCL4C_L.MIX
However, one can always use the large memory model library
PCL4C_L.LIB with any memory model application code by explicitly
declaring the PCL4C procedures to be FAR (by prefixing "far"
before the name of each function in the PCL4C.H file) and
declaring your receive buffer to be FAR. If you are compiling
with the HUGE memory mode, link with PCL4C_L.LIB.
The equivalent libraries with transmitter interrupts enabled are
PCL4C_S2.LIB, PCL4C_C2.LIB, PCL4C_M2.LIB, & PCL4C_L2.LIB.
PCL4C Users Manual Page 10
3.2 Compilers Supported
At this time, five C compilers are supported by PCL4C.
(1) Microsoft (Optimizing) C Compiler.
(2) Quick C Compiler.
(3) Turbo C Compiler.
(4) Borland C Compiler.
(5) MIX Power C Compiler
The Microsoft Optimizing C Compiler supports all memory models.
Just be careful to link with the PCL4C library that corresponds to
the memory model used. Recall that the small memory model is the
default. Examine the (small model) makefiles *._M_ for the
Microsoft compiler.
The Microsoft Quick C Compiler supports all memory models, but be
careful to link with the PCL4C library that corresponds with the
memory model used. Recall that the small memory model is the
default for the command line compiler (QCL) while the medium
memory model is the default for the interactive compiler
environment. Examine the (small model) makefiles *._Q_ for the
Microsoft Quick C compiler.
The Borland and Turbo C Compilers also supports all memory models.
Be sure to link with the correct PCL4C library corresponding to
the memory model used. Examine the (small model) makefiles *._T_
for the Turbo C compiler.
The MIX Power C Compiler supports the small, medium, and large
memory models. However, older versions of Power C only support the
small model. Examine the (small model) project batch files
X_*.BAT for the Power C Compiler.
Other compilers may also work with one or more of the PCL4C
libraries but have not been tested. Since registered users have
the source code to the library, it should not be difficult to
modify PCL4C for use with any MSDOS C compiler.
PCL4C Users Manual Page 11
3.3 Using the Library
The PCL4C has been tested on a TANDY 1000 (4.77 MHZ 8088 IBM PC
clone), a TANDY 3000 (80286 IBM AT clone), a TANDY 1400LT (IBM XT
clone), and a Gateway 2000 Cache (25 MHZ 80386-DX). PCL4C has
been tested under MSDOS 2.11, 3.2, 3.3, 4.01, and 5.0.
Please examine the PCL4C.H file. Note that COM1 is defined as port
zero, not port one. The user must assume the responsibilty for
passing the correct information when calling PCL4C functions.
If there are any conflicts between PCL4C definitions and those in
other libraries, the PCL4C definitions can be changed in the
PCL4C.H file and any file that uses the definition. There is no
change necessary for the library code itself.
3.4 Example Programs
Two communications programs are provided as a demonstration of the
PCL4C library -- SIMPLE and TERM.
SIMPLE is provided as the simpliest example of communications
programming using PCL4C. The user should compile and link SIMPLE.C
as a test of the library.
If you have two computers, connect them together with a null modem
cable and run SIMPLE on both machines. The baud rate in SIMPLE is
hard coded to 2400 baud. It is easily changed in the source code.
Start SIMPLE by typing SIMPLE followed by the port. For example:
SIMPLE 1
Once SIMPLE is started on both computers, whatever is typed on one
machine should be displayed on the other, and vice versa.
The TERM program is a more capable terminal emulator than SIMPLE.
It features modem initialization, hardware flow control, and file
transfer using ASCII, XMODEM, YMODEM, and YMODEM-G communications
protocols. TERM can be used to call up any bulletin board system,
including the MarshallSoft Computing BBS. Start TERM by typing
TERM followed by the port and baud rate. For example:
TERM 4 2400
Refer to the chapter "Terminal Emulator Program" for a complete
discussion of TERM.
Other example programs may be included on your distribution disk.
PCL4C Users Manual Page 12
3.5 Compiling and Linking
Registered users may wish to assemble PCL4C.ASM. Use the /MX
switch in order to disable automatic conversion from lower case to
upper case. If the /MX switch is not used, then all PCL4C
function references in C code must be in upper case. To assemble
using the Microsoft assembler:
Model Command
Small MASM PCL4C /DSMALL_MODEL /MX;
Compact MASM PCL4C /DCOMPACT_MODEL /MX;
Medium MASM PCL4C /DMEDIUM_MODEL /MX;
Large MASM PCL4C /DLARGE_MODEL /MX;
To enable transmitter interrupts, add "/DSET_TBE" to each MASM
command line above.
For example, to make the (small) model PCL4C.OBJ into a library
file:
DEL PCL4C_S.LIB
LIB PCL4C_S.LIB+PCL4C,PCL4C.MAP;
If you are using the MIX Power C Compiler, create the MIX object
file (you will need version 1.3 of MIX which has the /_ switch):
MIX /_ PCL4C_S
Similarly with the other memory model libaries. See the batch
files MAKE_S.BAT, MAKE_C.BAT, MAKE_M.BAT, and MAKE_L.BAT.
Similiarly for MAKE_ST.BAT, MAKE_CT.BAT, MAKE_MT.BAT, and
MAKE_LT.BAT.
To compile and link (small model) using Microsoft C:
cl /AS simple.c /link pcl4c_s.lib
To compile and link (small model) using Microsoft Quick C:
qcl /AS simple.c /link pcl4c_s.lib
To compile and link (small model) using Turbo C:
tcc -ms simple.c pcl4c_s.lib
To compile and link (small model) using Power C:
pc /ms simple.c
pcl simple pcl4c_s.mix
Makefiles or project files are provided for both SIMPLE and TERM.
Borland and Turbo C makefiles end with the extension '._T_',
Microsoft C makefiles end with '._M_', Microsoft Quick C
makefiles files end with '._Q_', and Power C project batch files
start with 'X_' and end with '.BAT'.
PCL4C Users Manual Page 13
4.0 Talking to Your Modem
A modem is used to extend the distance over which you may
communicate. Without a modem, your RS232 cable is limited to a
maximum of approximately 50 feet. But with a modem, you can
communicate literally around the world.
4.1 Modem Standards
Two modems can communicate over a telephone line only if they are
both using the same signaling frequencies and modulation, which
are determined by the the modem standards used. Modem standards
can be divided into three sets: (1) speed, (2) data compression
used, and (3) error control.
The Bell standards (103 & 212A) are those of AT&T. The CCITT (The
International Consultative Committee for Telephone and Telegraph)
standards are designated as "V. ".
Speed
Bell 103 -- 300 baud
Bell 212A -- 1200 baud
V.21 -- 300 baud
V.22bis -- 1200 & 2400 baud
V.32 -- 4800 & 9600 baud
V.32bis -- 4800, 7200, 9600, 12000, and 14400 baud
Data Compression
MNP 5 -- Microcom Networking Protocol (proprietary).
V.42bis -- International data compression standard.
Error Control
MNP 2,3,4 -- Three level error correction (public domain).
V.42 -- International error correction standard.
PCL4C Users Manual Page 14
4.2 Flow Control
With modems using data compression, the modem to modem connection
will run at various speeds depending on the quality of the line.
The computer to modem connection will be at a fixed baud rate.
Therefore, a protocol (flow control) is necessary to synchronize
the data flow between and modems and the computer to modem
connection. Refer to your modem manual for information on flow
control protocols supported.
Two flow control protocols are used by most all modems which
require flow control. Software flow control is called "XON/XOFF"
(other software flow control character pairs are defined but
operate the same as XON/XOFF) and hardware flow control is called
"RTS/CTS". Most modems which require flow control enable hardware
flow control by default.
In XON/XOFF (software) flow control, the computer suspends
transmitting data if it receives a XOFF character (13 hex) from
the modem, and continues transmitting when it receives a XON
character (11 hex). Similiarly, the computer can signal the modem
not to send any more data by transmitting a XOFF to it, and can
tell the modem to continue transmission be sending a XON.
In RTS/CTS (hardware) flow control, the RTS line is used by the
computer to signal the modem , while the CTS line is used by the
modem to signal the computer. The RTS line is set OFF by the
computer to tell the modem to suspend transmission, and set to ON
to tell the modem to continue transmission. The CTS line is set
to OFF by the modem to tell the computer to stop transmitting, and
set to ON to tell the computer to continue transmitting.
Given the choice, always choose hardware flow control over
software flow control so that all data transmission is
transparent. If hardware flow control is not the default (which
it almost always is), you should modify your modem initialization
string to turn hardware flow control on.
Both software and hardware flow control is easy to implement using
PCL4C. See TERM_IO.C for an example of hardware flow control.
PCL4C Users Manual Page 15
4.3 Modem Initialization
If your application uses a modem (as opposed to using a null modem
cable), then you should always send an initialization string to
your modem if it is a programmable modem such as those made by
Hayes. Communication programs such as PROCOMM and TELIX always
send such a string automatically as soon as they start up.
The particular initialization string depends on the make of your
modem. For Hayes and Hayes AT command set compatible modems, the
following string (followed by a carriage return) should work:
AT E1 S7=60 S11=60 V1 X1 Q0 S0=0
Refer to your Modem User's Guide for a full discussion of these
commands. A brief description is as follows:
AT Modem attention command.
E1 Modem will echo what you send to it.
S7=60 Wait 60 seconds for carrier and/or dial tone.
S11=60 Use 60 milliseconds for tone dialing duration & spacing.
V1 Display result code as words (not numbers).
X1 Use the extended result message (CONNECT XXXX) set.
Q0 Modem returns result codes.
S0=0 Do not answer RING.
If your application will answer incoming calls, then set the S0
register to the ring on which to automatically answer.
If you send the above codes by using SioPutc (as opposed to typing
them from the keyboard), then follow these guidelines:
(1) Send an initial carriage return before the initialization
string.
(2) Pause at least two tics (18 tics to the second) after each
character sent as your modem needs the time to perform its own
internal processing. Pause a little longer if your modem is not
accepting your initialization string.
(3) Pause one and a half seconds after sending any initialization
command such as ATZ or AT&F since your modem must do quite a bit
of processing.
If you experience any problems in initializing your Hayes modem,
you should first reset it to factory settings by sending:
AT&F
Refer to the TERM program (functions SendTo and WaitFor in the
file MODEM_IO.C) for an example of sending an initialization
string to a Hayes compatible modem.
PCL4C Users Manual Page 16
5.0 Problems
If you cannot get your application to run properly, first compile
and run the terminal emulator program TERM provided on your
distribution disk. If you are using a null modem cable or a
non-programmable modem, be sure to set the HAYES constant to 0 in
the source code (#define AT_COMMAND_SET 0). If you are using a
Hayes compatible modem, set the AT_COMMAND_SET constant to 1. If
you are using a programmable modem which is not Hayes compatible,
then you must modify the initialization string for your particular
modem.
If your application does not run but TERM runs correctly, then you
have most likely made a programming mistake in your application.
MarshallSoft Computing cannot debug your application, especially
over the telephone! However, consider each of the following when
searching for an error in your application.
1. Have you included the file PCL4C.H in your application ?
2. Did you link with the correct PCL4C library ? This is the
most probable cause if your application 'hangs' as soon as it
starts and you must reboot. The function SioInfo() returns the
the model ID under which the library was assembled.
3. Is your receive buffer large enough ? If you are using 1K data
blocks in YMODEM, then your receive buffer should be at least
1K (2K if baud rates above 19200 are to be used).
4. Have you selected too high a baud rate (if you are using a
slow PC) ? If only one COM port is being run, you should be
able to run at 38400 baud on 8088 machines and 115200 on most
286 and all 386 and 486 machines.
5. Are you attempting to run another application in the
background ? Try running without any other programs running
in the background (unload all TSR programs).
6. If you are running two COM ports simultaneously, are you using
separate receive buffers ? (you should).
7. Did SioReset return a zero value ? If not, then you must call
SioReset again. See TERM.C for an example.
8. Did you send the proper initialization string to your modem ?
Did you set DTR and RTS ? (you should).
9. Do you have more than one COM1 port, etc. For example, if you
have a COM1 port on your motherboard, you cannot add another
COM1 port or modem board that uses COM1 without first
disabling the COM1 on the motherboard.
10. Your first comm port should be COM1. If you have a second
port, it should be COM2, not COM3 or COM4.
PCL4C Users Manual Page 17
6.0 Serial Communications
6.1 Communications Basics
The heart of serial communications is the UART (Universal
Asynchronous Receiver Transmitter). The IBM PC/XT/AT and
compatibles use the INS8250, INS16450, or the INS16550 UART. The
purpose of the UART is:
(1) To convert bytes from the CPU (Central Processing Unit), into
a serial format by adding the necessary start, stop, and parity
bits to each byte before transmission, and to then transmit each
bit at the correct baud rate.
(2) To convert the incoming stream (at a specified baud rate) of
serial bits into bytes by removing the start, stop, and parity
bits before being made available to the CPU.
The UART is part of the serial interface circuitry which allows
the CPU to send and receive signals over the RS232 lines. This can
be diagrammed as follows:
Serial Interface
*********************
* *
******* Data Bus * ******** * RS232 Signals
* CPU ************** * UART * ******************
******* * ******** *
* *
*********************
The INS8250/16450/16550 UART is capable of operating in one of
two modes, "polled" and "interrupt driven". The serial
communications functions in the BIOS uses the polled method. In
this approach, the CPU is typically in a loop asking the UART
over and over again if it has a byte ready. If its does, the
polling code returns the byte. But, if the next byte comes in
before the polling code is executing again, then that byte is
lost.
In the interrupt driven approach (used by PCL4C for incoming
data), when a byte is received by the UART, an "Interrupt Service
Routine" (ISR) is executed immediately, suspending temporarily
whatever else is executing. The ISR then moves the byte to a
buffer so that your application program can later read it. Refer
to the sections entitled "RS232 Signals" and "National INS8250
UART" for further information on these topics.
PCL4C Users Manual Page 18
6.2 Standard Port Addresses
There are a few things to know about how serial communications
ports are used by IBM PC/XT/AT and compatible computers. The
standard IBM PC/XT/AT configuration values are as follows:
Port Reg Base IRQ Line Vector
COM1 3F8H 4 12
COM2 2F8H 3 11
COM3 3E8H 4 12
COM4 2E8H 3 11
(Refer to your DigiBoard manual for DigiBoard addresses).
PCL4C assumes the above values. If necessary, the UART base
address can be changed by SioUART, and IRQ lines can be
re-assigned by SioIRQ. Remember that each port to be used
concurrently must have a unique IRQ line. Refer to the PCL4C
Reference Manual for specific details.
When installing new communications cards, the following guidelines
are recommended:
(1) Be sure to read the documentation for the hardware you are
installing. Pay special attention to UART base addresses and IRQ
lines, particularly if trying to set up a non-standard
configuration.
(2) If you have a choice in base addresses and IRQ lines, always
choose standard values as defined above.
(3) The first port should be COM1, the second COM2, etc. Do NOT
skip over any port.
(4) Use SioUART to zero all unused ports (for example, call
SioUART(COM4,0) if there is no COM4 port installed).
(5) Be carefull not to configure two ports for the same address.
This is easier to do than you may believe.
(6) Choose an external modem over an internal one. It is much
easier to debug problems with an external modem than an internal
one.
(7) Select hardware flow control (RTS/CTS) if flow control is
required and hardware flow control is not the default.
(8) Always test your port as soon as it is installed. Try several
programs that use the communications ports.
PCL4C Users Manual Page 19
6.3 Running 3 or 4 Ports Concurrently
PCL4C supports up to 4 serial ports running concurrently (more if
you have a DigiBoard). One free interrupt for each port is
required. Refer to the next section if you have a DigiBoard.
Interrupts IRQ4 and IRQ3 are dedicated to the communications ports
in a standard IBM PC/XT/AT configuration. IRQ4 is shared between
COM1 and COM3 while IRQ3 is shared between COM2 and COM4. This
means that you can run two ports simultaneously provided that they
don't share an interrupt.
Suppose that you wish to run 3 ports simultaneously. To begin, you
must have 3 serial UARTs installed on your computer. Assume, for
purposes of this discussion, that COM1 is installed on your
motherboard, and that you have purchased a new 2 port
serial communications board.
You should be able to configure the first serial board port as
COM2, which uses IRQ3. Refer to the manual that came with your
serial board.
In order to run the third serial port concurrently with the first
two, an unused interrupt must be found. If your serial card can
use only IRQ3 and IRQ4, then there is no way to run a third line
since IRQ4 and IRQ3 are used for COM1 and COM2.
However, many serial cards can use other IRQs, typically IRQ2
through IRQ5. Since IRQ5 is normally used for a second printer
port, it is a good candidate for COM3. To use IRQ5 for the third
serial port, first set your serial card to use IRQ5 for COM3
(refer to your serial card manual) and then add the following line
to your applications code before calling SioReset:
SioIRQ(COM3,IRQ5);
Don't forget to disable any device that might use IRQ5, such as a
second printer port or a music card. Unfortunately, there is no
easy way to determine that you have no conflicts until you
actually attempt to use the IRQ. If there are conflicts, your
system will probably hang and you will have to reboot.
To run a fourth serial port, another free IRQ must be found. On
some systems, IRQ2 can be used. To use IRQ2 for the fourth serial
port, first set your serial card to use IRQ2 for COM4 and then
add:
SioIRQ(COM4,IRQ2);
To summarize, your serial card must be able to generate the
correct IRQ, which is not already being used. Refer to the entry
for the SioIRQ function in the PCL4C Reference Manual.
PCL4C Users Manual Page 20
6.4 Using the DigiBoard
The Personal Communications Library supports the DigiBoard PC/4
and PC/8. In order to use the DigiBoard, you must configure PCL4C
using the SioPorts(), SioUART(), and SioIRQ() functions.
Your PCs ports must be partitioned into "standard" PC ports and
DigiBoard ports. Remember that standard PC ports cannot share
IRQs like the DigiBoard can. If you are using IRQ4 and IRQ3 for
standard PC ports COM1 and COM2, then you cannot use either for
DigiBoard ports (try IRQ5 or IRQ2).
Suppose that COM1 through COM2 are standard PC ports (using IRQ4
and IRQ3) and you have installed a PC/8 DigiBoard that you wish to
use for COM3 through COM10 using interrupt line IRQ5. You choose
to use the recommended DigiBoard UART addresses at 0x100, 0x108,
0x110, 0x118, 0x120, 0x128, 0x130, and 0x138. Add the following
configuration statements before doing any other serial processing:
SioPorts(10,COM3,0x140); /* COM3 is first DigiBoard port */
Address = 0x100; /* first DigiBoard UART address */
for(Port=COM3;Port<=COM10;Port++) /* look at each port */
{SioUART(Port,Address); /* set the UART address */
Address += 8; /* compute next address */
SioIRQ(Port,IRQ5); /* set the DigiBoard IRQ */
}
The DigiBoard uses 0x140 for the status address for odd interrupts
and 0x141 for even interrupts. Thus 0x140 is used for the status
address since IRQ5 is used for the interrupt in the example above.
Don't forget that your DigiBoard hardware must be configured to
match the IRQ and UART values that you specify in the library.
Refer to your DigiBoard manuals for more information.
The PCL4C library comes configured for 4 PC ports and no DigiBoard
ports -- SioPorts(4,4). Refer to the PCL4C Reference Manual for
more detailed information on SioPorts(), SioUART(), and SioIRQ().
If you are interested in the DigiBoard, they may be contacted at
6400 Flying Cloud Drive, Eden Prairie, MN 55344. Telephone
612-943-9020 or FAX 612-943-5398.
PCL4C Users Manual Page 21
6.5 Transmitter Interrupts
Beginning in version 4.0 of PCL4C, transmitter interrupts are
supported by the library. Separate libraries are provided, one
with transmitter interrupts enabled and one without. When
transmitter interrupts are NOT enabled, the following logic occurs
everytime you call SioPutc():
1. Wait for transmit buffer to become empty. The transmit
buffer may not be empty if the previous transmit is not
completed (the UART breaks down the byte & sends 1 bit
at a time).
2. When the transmit buffer is empty, the byte from the
SioPutc() call is loaded into the transmit buffer and
control is returned to the caller.
Note that you can not write to the UART any faster the the UART
baud rate.
When transmitter interrupts are enabled, the byte from SioPutc()
is put into a previously prepared (by SioTxQue) transmitter queue.
The interrupt service routine fetches bytes from this queue as
soon as the previous byte has been sent.
While you can now call SioPutc() faster than the baud rate, bytes
are still transmitted at the given baud rate.
The above sounds like transmitter interrupts are the way to go.
Unfortunately, this is usually NOT the case. Most applications
will perform better if transmitter interrupts are NOT enabled.
The reason is that transmitter interrupts double the amount of
code in the time critical interrupt service routines. While the
library is processing a transmitter interrupt (which can take a
while), incoming bytes can not be processed. What this means is
that a given machine can run at a higher baud rate without
transmitter interrupts. This problem is compounded when running
multiple ports simultaniously.
However, there are a few application areas where transmitter
interrupts are preferable. If your application will be
transmitting blocks of data at fairly slow baud rates you might
profit from enabling transmitter interrupts provided that there is
something else for the processor to do (which is NOT the case in
most protocols).
Recall that PCL4C_S2.LIB (small), PCL4C_C2.LIB (compact),
PCL4C_M2.LIB (medium), and PCL4C_L2.LIB (large) are the four
memory model libraries with transmitter interrupts enabled.
PCL4C Users Manual Page 22
6.6 RS-232 Signals
RS-232 is the name of the serial data interface standard used to
connect computers to modems. Most IBM compatible computers are
built with at least one serial port and use either DB9 (9 pin) or
DB25 (25 pin) connectors.
A summary of these pins and their function follows. For more
detailed information, refer to one of the many books dealing with
RS-232 interfacing.
Signal Ground Pin 7 (DB25), Pin 5 (DB9)
The SG line is used as the common signal ground, and must always
be connected.
Transmit Data Pin 2 (DB25), Pin 3 (DB9)
The TX line is used to carry data from the computer to the modem.
Receive Data Pin 3 (DB25), Pin 2 (DB9)
The RX line is used to carry data from the modem to the computer.
Data Terminal Ready Pin 20 (DB25), Pin 4 (DB9)
The DTR line is used by the computer to signal the modem that it
is ready. DTR should be set high when talking to a modem.
Data Set Ready Pin 6 (DB25), Pin 6 (DB9)
The DSR line is used by the modem to signal the computer that it
is ready.
Request to Send Pin 4 (DB25), Pin 7 (DB9)
The RTS line is used to "turn the line around" in half duplex
modems, and for hardware flow control in most modems that require
flow control.
Clear to Send Pin 5 (DB25), Pin 8 (DB9)
The CTS line is used to "turn the line around" in half duplex
modems, and for hardware flow control in most modems that require
flow control.
Data Carrier Detect Pin 8 (DB25), Pin 1 (DB9)
The DCD line is used by the modem to signal the computer that a
data carrier signal is present.
Ring Indicator Pin 22 (DB25), Pin 9 (DB9)
The RI line is asserted when a 'ring' occurs.
PCL4C Users Manual Page 23
6.7 National INS8250, INS16450, and INS16550 UARTs
The Personal Communications Library is based on the standard
National INS8250, INS16450, and INS16550 UARTs. The 8250 was the
original UART used in the IBM PC, whereas the 16450 is a faster
version found on most 286 & up machines. The 16550 contains a 16
byte FIFO to further reduce communications overhead. These UARTs
consists of 8 register ports as follows:
Offset R/W Register
0 R/W Receiver (read) / Transmitter (write)
1 R/W Interrupt Enable (read)
2 R Interrupt Identification
2 W FIFO control (INS16550 only)
3 R/W Data Format (Line Control)
4 R/W RS-232 (Modem) Control
5 R/W Line Status
6 R/W RS-232 (Modem) Status
7 R/W Not used.
For the standard PC ports (not DigiBoard ports), the UART
registers are based at 3F8h (COM1), 2F8h (COM2), 3E8h (COM3), and
2E8h (COM4). COM1 and COM3 share interrupt request line IRQ4
while COM2 and COM4 share request line IRQ3. This means that COM1
and COM3 can't be used concurrently. Similarly for COM2 and COM4.
If you have a DigiBoard PC/4 (or PC/8) installed, you will have 4
(or 8) additional ports using INS16450 or INS16550 UARTS. The
default DigiBoard ports are located at 100h, 108h, 110h & 118h for
the PC/4 continuing with 120h 128h, 130h & 138h for the PC/8. IRQ3
is the default for all ports.
Four sources of interrupts are possible with the 8250 and 16550:
(1) receiver error or BREAK, (2) receiver data ready, (3) ready to
transmit, and (4) RS232 input. These four sources of interrupts
are summarized as follows:
Source of Interrupt Action Required to Clear
Receiver error or BREAK. Read Line Status register.
Receiver data. Read data from data register.
Transmitter Buffer Empty. Write to data register or read IID reg.
RS232 input. Read Modem Status register.
However, PCL4C only enables the receiving data interrupt. This
means that interrupts can only be caused by incoming data.
If you are not familiar with the INS8250, several good books are
available. Refer to the Serial Communications chapter for
recommendations. Although a knowledge of the 8250 is not
necessary to use PCL4C, a general knowledge of the theory of
asynchronous serial communications is recommended.
PCL4C Users Manual Page 24
6.8 Register Summary
REG 0 : Data Register
Reading from the data register fetches the next input byte, once
it is ready. Writing to the data register transmits the byte
written to it over the serial line.
REG 1 : Interrupt Enable
The Interrupt Enable register enables each of four types of
interrupts when the appropriate bit is set to a one.
bit 3 : Enable interrupt on RS232 input.
bit 2 : Enable interrupt on receiver error or break.
bit 1 : Enable interrupt on transmitter buffer empty (TBE).
bit 0 : Enable interrupt on received data (RxRDY).
REG 2 : Interrupt Identification (IID)
Reading the Interrupt Identification (read only) register once
an interrupt has occurred identifies the interrupt as follows:
Bit 2 Bit 1 Bit 0 Priority Interrupt
0 0 1 none none
1 1 0 0 (high) Serialization or break.
1 0 0 1 Received data.
0 1 0 2 Transmitter Buffer Empty.
0 0 0 3 (low) RS232 Input.
In the INS16650, REG 2 (write only) is also the FIFO control
register. Writing bits 6 & 7 will set the FIFO trigger level
(number of bytes received before an interrupt is generated).
Bit 7 Bit 6 Trigger Bit 7 Bit 6 Trigger
0 0 1 byte 1 0 8 bytes
0 1 4 bytes 1 1 14 bytes
REG 3 : Line Control
RS232 line parameters are selected by writing to this register.
bit 7 : DLAB = 0
bit 6 : BREAK on(1), off(0).
bits 5-3: Parity None(000),ODD(001),EVEN(011),MARK(101),SPACE(111)
bit 2 : One stop bit(0), two stop bits(1).
bits 1-0: Data bits = 5 (00), 6(01), 7(10), 8(11).
When the Divisor Latch Access Bit (DLAB) is 1, registers 0 and 1
become the LS and MS bytes of the Baud Rate Divisor registers.
Baud Divisor Baud Divisor Baud Divisor
300 0180 4800 0018 38400 0003
1200 0060 9600 000C 57600 0002
2400 0030 19200 0006 115200 0001
PCL4C Users Manual Page 25
REG 4 : Modem Control
RTS, DTR, loopback testing, and General Purpose Outputs #1 and #2
are controlled by the Modem Control register as follows:
bit 4 : Enable local loopback.
bit 3 : Enable GP02. Necessary for 8250 interrupts.
bit 2 : Enable GP01.
bit 1 : Set / clear RTS.
bit 0 : Set / clear DTR.
REG 5 : Line Status
Reading the Line Status register provides status information as
follows (1 for TRUE, 0 for FALSE) :
bit 6 : Transmitter Empty.
bit 5 : Transmitter Buffer Empty (TBE).
bit 4 : BREAK detect.
bit 3 : Framing error.
bit 2 : Parity error.
bit 1 : Overrun error.
bit 0 : Data Ready.
REG 6 : Modem Status
Reading the Modem Status register provides the following status
information (1 for TRUE, 0 for FALSE) :
bit 7 : DCD status.
bit 6 : RI status.
bit 5 : DSR status.
bit 4 : CTS status.
bit 3 : Delta DCD status.
bit 2 : Delta RI status.
bit 1 : Delta DSR status.
bit 0 : Delta CTS status.
The delta bits (bits 0 through 3) are set whenever one of the
status bits (bits 4 through 7) changes (from 0 to 1 or from 1 to
0) since the last time that the Modem Status register was read.
Reading the Modem Status register clear the delta bits.
REG 7 : Scratch Register
There is no function associated with register 7. It does not
exist in early versions of the 8250.
PCL4C Users Manual Page 26
7.0 Terminal Emulator Example Program
TERM is an communications program suitable for calling bulletin
board systems (BBS) and performing as a PC to PC file copy
program. TERM itself is not part of the communications library,
but rather it is provided as an example of a communications
application using PCL4C.
TERM can send a standard Hayes standard AT command set string to
your modem. An initialization string is sent by TERM provided
that the constant AT_COMMAND_SET in the file TERM.CFG is defined
to be TRUE:
#define AT_COMMAND_SET 1
Refer to the chapter "Modem Initialization" for a discussion of
initialization strings.
TERM also supports hardware flow control (RTS/CTS). Hardware flow
control is observed provided that the constant RTS_CTS_CONTROL in
the file TERM.CFG is defined to be TRUE:
#define RTS_CTS_CONTROL 1
Refer to the chapter "Flow Control" for a discussion of hardware
flow control.
TERM can also exchange files using ASCII (with XON/XOFF), XMODEM,
YMODEM (batch capability), and YMODEM-G (streaming YMODEM used
with error correcting modems) communications protocols. TERM can
accept wildcards in the filename so that multiple files can be
sent using YMODEM and YMODEM-G. The protocol timing can also be
adjusted (this should not be necessary) by modifying the constants
SHORT_WAIT and LONG_WAIT in the TERM.CFG file.
TERM can also be used as a PC to PC transfer program using a null
modem cable. In this case, AT_COMMAND_SET and RTS_CTS_CONTROL
should be defined to be FALSE in the file TERM.CFG:
#define AT_COMMAND_SET 0
#define RTS_CTS_CONTROL 0
Be advised that most null modem cables are do NOT swap RTS and
CTS, which is necessary for hardware flow control. This means that
RTS_CTS_CONTROL should never be set to 1 (TRUE) when using a null
modem cable unless you are absolutely sure that RTS and CTS are
swapped.
To start TERM, type TERM followed by the port (1 to 4) and the
baud rate (300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600,
or 115200). For example, to start TERM at 2400 baud on port COM4:
TERM 4 2400
The TERM program (but of course not the library itself) is placed
in the public domain by MarshallSoft Computing, Inc., and can be
used in any way desired by the user.
PCL4C Users Manual Page 27
8.0 Legal Issues
8.1 Registration
If you wish to register the PCL4C library, please send $55 plus $3
S&H ($6 outside of North America) to:
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815
Multiple copies are available: $45 for 3 to 9, $35 for 10 to 19,
and $25 for 20 or more. A site license is also available for $495
(includes 5 sets of printed documentation). We pay shipping.
We accept American Express (account number, expiration date,
exact name on your card, and complete AmEx billing address
required), checks in US dollars drawn on a US bank, purchase
orders (POs) from recognized US schools and companies listed in
Dun & Bradstreet, and COD (street address and phone number
required) within the USA (plus a $3 COD charge). Print the file
PCL4C.INV if an invoice is needed.
You can also order PCL4C from The Public Software Library (PSL)
with your MC, Visa, AmEx, or Discover card by calling 800-242-4PSL
(from overseas: 713-524-6394) or by FAX at 713-524-6398 or by
CompuServe at [71355,470]. THESE NUMBERS ARE FOR ORDERING ONLY.
The product number for PCL4C is 10908.
If you wish to update from an older version of PCL4C, send $15
plus $3 S&H ($6 outside of North America). Updates must be
ordered directly from MarshallSoft Computing.
The registered package includes:
o Small,Compact,Medium, & Large libs w/o shareware screens.
o Assembler source code for the library.
o Laser printed Users and Reference Manuals.
o Telephone, FAX, and BBS support for one year.
o EXAMPORT -- Free utility which displays a detailed formatted
report for any serial port. For example, to display a report
for COM1, type "EXAMPORT 1".
Print the file PCL4C.INV if an invoice is needed. The registered
user will receive the latest version of PCL4C shipped by two day
priority mail (packet airmail overseas). A 5.25" diskette is
provided unless a 3.5" diskette is requested.
8.2 Referral Program
The registered user will receive a $5 certificate towards any
MarshallSoft Computing product by referring a new customer
(someone who has never registered with us). The new customer must
identify you at the time the full price order is placed. You will
be mailed a $5 certificate when the new registration is paid.
PCL4C Users Manual Page 28
8.3 License
MarshallSoft Computing, Inc. grants the registered user of PCL4C
the right to use one copy of the PCL4C library (in object form) on
a single computer in the development of any software product
(other than libraries such as PCL4C). The user may not use the
library on more than one computer at the same time. The source
code for the library (PCL4C.ASM) is copyrighted by MarshallSoft
Computing and may not be released in whole or in part. Products
developed using PCL4C may be distributed without any royalty.
8.4 Warranty
MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING TO
THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT
LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY
AND SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING, INC.
NOR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION,
OR DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT,
CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR
INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING,
INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR
CLAIMS. IN NO EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY
FOR ANY SUCH DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO
USE THE SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON
USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND
PERFORMANCE OF THE SOFTWARE.
Some states do not allow the exclusion of the limit of liability
for consequential or incidental damages, so the above limitation
may not apply to you.
This agreement shall be governed by the laws of the State of
Alabama and shall inure to the benefit of Marshallsoft Computing,
Inc. and any successors, administrators, heirs and assigns. Any
action or proceeding brought by either party against the other
arising out of or related to this agreement shall be brought only
in a STATE or FEDERAL COURT of competent jurisdiction located in
Madison County, Alabama. The parties hereby consent to in personam
jurisdiction of said courts.
PCL4C Users Manual Page 29
9.0 Summary
9.1 Revision History
Version 1.0 -- 14 January 1991 -- original release.
Version 1.1 -- 11 March 1991
o Added SioUnGetc() function to library.
Version 1.2 -- 1 June 1991
o SioParms() bug -- could not call before SioReset.
o SioReset() bug -- was not saving & restoring all regs.
Version 1.3 -- 1 July 1991
o Added NORESET option to SioReset.
o Added SioDSR, SioCTS, SioDCD, SioLoopBack, and SioRI.
Version 2.0 -- 1 Nov 1991
o Reorganized as four memory model libraries.
o Added SioModel function to library.
o Added support for Quick C and Power C.
Version 2.1 -- 1 Dec 1991
o Fixed bug due to Microsoft Assembler (MASM 5.0,5.1) error.
NOTE: MarshallSoft incorporated as "MarshallSoft Computing, Inc."
on December 23rd, 1991.
Version 3.0 -- 15 Jan 1992
o Added SioUART function.
o Added "UART undefined" error code.
o Added "Bad or missing UART" error code.
o Added "Port already enabled" error code.
o Added "Cannot enable both COM1 & COM3 ..." error code.
o Fixed several minor bugs (using new automated testing).
Version 3.1 -- 1 March 1992
o Added SioFIFO (INS16550 support).
o Added SioIRQ function.
o Increased maximum receive buffer size to 32K bytes.
PCL4C Users Manual Page 30
9.1 Revision History (continued)
Version 3.2 -- 1 May 1992
o Modified SioReset so that it no longer clears DTR & RTS.
o Modified SioModel & renamed to SioInfo.
o Fixed bug in SioDone when using 2 ports simultaneously.
o Added SioFlow to library.
o Added YMODEM-G protocol to TERM program.
Version 3.3 -- 3 August 1992
o Fixed bug in SioUnGet when using 2 ports simultaneously.
o Add SioRead function.
Version 3.4 -- 4 Jan 1993
o Library modified to use up to four ports simultaneously.
o SioIRQ was modified to include a third argument.
o EXAMPORT utility distributed to registered users.
Version 3.5 -- 15 May 1993
o Supports DigiBoard PC/4 and PC/8.
o Two new error traps added ("No such IRQ" & "No such ISR").
o ASCII file transfer protocol added to TERM (with XON/XOFF).
Version 4.0 -- 18 Oct 1993
o The library supports transmitter interrupts.
o Corrects bug in Ver 3.5 requiring calling SioIRQ for COM3/4.
o All example code compiles with supported C++ compilers.
o The SioIRQ() function has been simplified.
PCL4C Users Manual Page 31
9.2 Function Summary
Refer to the PCL4C Reference Manual (PCL4C.REF) for detailed
information on the communications and support functions. A one
line summary of each function follows:
SioBaud Sets the baud rate of the selected port.
SioBrkKey Returns non-zero if the Control-BREAK key was pressed.
SioBrkSig Asserts, cancels, or detects BREAK signal.
SioCrtWrite Write character to the screen.
SioCTS Reads the Clear to Send (CTS) modem status bit.
SioDCD Reads the Data Carrier Detect (DCD) modem status bit.
SioDelay Delays one or more tics (18 tics per second).
SioDone Terminates further serial processing.
SioDSR Reads the Data Set Ready (DSR) modem status bit.
SioDTR Set, clear, or read the Data Terminal Ready (DTR) bit.
SioError Displays error in text.
SioFIFO Sets the interrupt level for the INS16550.
SioFlow Enables / disables hardware flow control.
SioGetc Reads the next character from the serial line.
SioKeyPress Detects if keyboard has been pressed.
SioKeyRead Reads the keyboard.
SioInfo Returns library version number & memory model.
SioIRQ Assigns an IRQ line to a port.
SioLine Reads the line status register.
SioLoopBack Performs a UART loopback test.
SioModem Reads the modem status register.
SioParms Sets parity, stop bits, and word length.
SioPorts Sets # ports, 1st DigiBoard port & status register.
SioPutc Transmit a character over a serial line.
SioRead Reads any of 7 UART ports.
SioReset Initialize a serial port for processing.
SioRI Reads the Ring Indicator (RI) modem status bit.
SioRTS Sets, clears, or reads the Request to Send (RTS) line.
SioRxBuf Sets up receive buffer.
SioRxFlush Flushes (clears) the receive buffer.
SioRxQue Returns the number of characters in the receive queue.
SioTimer Returns the number of system clock tics.
SioTxBuf Sets up transmit buffer.
SioTxFlush Flushes (clears) the transmit buffer.
SioTxQue Returns the number of characters in the transmit queue.
SioUART Sets the UART base address.
SioUnGetc "Un-gets" (puts back) a specified character.
9.3 Further Reading
The best way to learn about serial communications is to read a
good book on the subject. Several good texts are available. Two
that I like are:
(1) C Programmers's Guide to Serial Communications by Joe Campbell
(SAMS)
(2) Mastering Serial Communications by Peter Gofton (SYBEX).
PCL4C Users Manual Page 32
10.0 Other MarshallSoft Computing Products
10.1 The Personal Protocol Library for C
The Personal Protocol Library for C (PPL4C) consists of a state
driven C language library which implements XMODEM, XMODEM-CRC,
XMODEM-1K, XMODEM-G, YMODEM, and YMODEM-G file transfer protocols.
This allows the communications application to run four ports
simultaneously while interacting with the user at the keyboard.
The state driven library functionally emulates background tasking
of protocols with standard MSDOS.
The primary application area for the protocol library is in the
development of custom BBS programs (and programs that call BBS's)
which require either multiple lines or which require user
interaction while a file transfer is underway. The state driven
architecture can also be used as a framework and guide to
developing customized file transfer protocols.
The protocol library (PPL4C) requires the C communications library
PCL4C. The PPL4C comes with fully commented C source code, an
example program which can transmit or receive two files
simultaneously, printed documentation, and one year of telephone,
FAX, and BBS support.
The Personal Protocol Library for C is available for $35 plus $3
S&H ($6 S&H overseas). It can also be ordered together with the C
communications library for $75 for both, plus $3.50 S&H ($7
overseas).
10.2 The LZW Data Compression Library for C
LZW4C is an implementation of the LZW (Lempel-Ziv-Welch) algorithm
for compressing and decompressing data. LZW does particularly
well on text files, achieving better than a 50 % compression ratio
for many files.
The LZW algorithm is considered to be one of the best general
purpose algorithms available today. The new high speed modems
that employ on-the-fly data compression (such as MNP 5.0 & the
V.42 bis international standard) use the LZW algorithm, as well as
such well known utility programs such as PKZIP.
The LZW Data Compression Library for C is available for $35 plus
$3 S&H ($6 S&H overseas).
PCL4C Users Manual Page 33
10.3 The EMS Expanded Memory Library
The EMS4C library implements version 3.2 of the LIM
(Lotus-Intel-Microsoft) specification for expanded memory. It will
run with either version 3.2 or 4.0 of the LIM specification.
The EMM4C library (included with the EMS4C library) is an expanded
memory manager which allows C programmers to allocate and free EMS
(expanded) memory similiar to malloc() and free() in the standard
C runtime library. Both EMM4C and EMS4C require that your system
be configured with expanded (EMS) memory. But, 386 & up systems
can use extended memory as expanded memory.
The EMS Expanded Memory Library for C is available for $35 plus $3
S&H ($6 S&H overseas).
PCL4C Users Manual Page 34
